home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Add-Ons / MPW / MPW noweb 2.7 / src / xdoc / noindex.1 < prev    next >
Encoding:
Text File  |  1995-05-30  |  3.1 KB  |  161 lines  |  [TEXT/MPS ]
  1. .TH NOWEB 1 "local 4/19/93"
  2. .SH NAME
  3. noindex \- build external index for noweb document
  4. .SH SYNOPSIS
  5. .B noindex \fIbasename\fP\fR[\fP.tex\fR]
  6. .SH DESCRIPTION
  7. .I noindex
  8. looks through 
  9. .I LaTeX
  10. .B .aux
  11. files for identifiers that should go in a
  12. .I noweb
  13. external index.
  14. It sorts all identifiers and writes the results on
  15. .I basename\fB.nwi\fP.
  16. .SH NOWEB INDEXING STRATEGIES
  17. A 
  18. .I noweb
  19. program consists of one or more files.
  20. In the simple case, these files are run through
  21. .I noweave
  22. together, to produce a single
  23. .I LaTeX
  24. file.
  25. .I noweave \-index
  26. suffices to produce an index and cross-referencing information;
  27. neither 
  28. .I nodefs
  29. nor
  30. .I noindex
  31. is required.
  32. .PP
  33. When a 
  34. .I noweb
  35. program
  36. consists of several source files, it is often better to run each source file
  37. through 
  38. .I noweave
  39. to produce its own 
  40. .I LaTeX 
  41. file, then use
  42. .I noindex
  43. to produce an external index.
  44. This technique has several advantages:
  45. .IP
  46. The line numbers in the 
  47. .I LaTeX
  48. files correspond to the line numbers in the source files, so it is easier
  49. to diagnose 
  50. .I LaTeX
  51. errors.
  52. .IP
  53. The
  54. .I LaTeX
  55. .B "\\\\includeonly"
  56. feature can be used, making it possible to format parts of large programs while retaining
  57. complete cross-reference information.
  58. .IP
  59. When used with
  60. .I make(1),
  61. the technique 
  62. avoids running 
  63. .I noweave
  64. over source files that have not changed.
  65. .IP
  66. Using the external index places fewer demands on \fILaTeX\fP's memory,
  67. making it read its
  68. .B .aux
  69. files much more quickly.
  70. .PP
  71. The disadvantages are that 
  72. .I nodefs
  73. and 
  74. .I noindex
  75. are needed for full cross-referencing and a properly sorted index.
  76. .SH EXAMPLE
  77. This example assumes a 
  78. .I noweb
  79. program of three source files:
  80. .B a.nw, b.nw, 
  81. and
  82. .B c.nw.
  83. The file
  84. .B doc.tex
  85. is assumed to contain 
  86. .I LaTeX
  87. boilerplate, including the commands
  88. .IP
  89. \\noweboptions{externalindex}
  90. .nf
  91. \\include{a}
  92. \\include{b}
  93. \\include{c}
  94. .fi
  95. .PP
  96. The first sequence of steps is to create a file listing all the
  97. identifiers defined anywhere in 
  98. .B a, b,
  99. or 
  100. .B c.
  101. .IP
  102. nodefs a.nw > a.defs
  103. .nf
  104. nodefs b.nw > b.defs
  105. nodefs c.nw > c.defs
  106. sort -u a.defs b.defs c.defs | cpif all.defs
  107. .fi
  108. .PP
  109. Using
  110. .I sort -u
  111. and
  112. .I cpif(1)
  113. avoids changing
  114. .B all.defs
  115. unless the set of identifiers changes.
  116. This technique, used in a Makefile, avoids unnecessary rebuilding.
  117. .PP
  118. The next series of steps is to create
  119. .I LaTeX
  120. files with full cross-reference information for all identifiers.
  121. .IP
  122. noweave -n -indexfrom all.defs a.nw > a.tex
  123. .nf
  124. noweave -n -indexfrom all.defs b.nw > b.tex
  125. noweave -n -indexfrom all.defs c.nw > c.tex
  126. .fi
  127. .PP
  128. The final steps run
  129. .I LaTeX
  130. once to create
  131. .B .aux
  132. files, then
  133. .I noindex 
  134. to create the index,
  135. then
  136. .I LaTeX
  137. again to format the complete document.
  138. .IP
  139. latex doc
  140. .nf 
  141. noindex doc
  142. latex doc
  143. .fi
  144. .PP
  145. In a Makefile,
  146. .I noindex
  147. can be run before every invocation of
  148. .I LaTeX.
  149. .SH BUGS
  150. .I noindex
  151. is distributed in awk and Icon versions.
  152. The awk version is slow and does a poorer job sorting.
  153. .PP
  154. There is no comparable machinery to make it possible to use multiple files 
  155. with the HTML back end.
  156. .SH SEE ALSO
  157. .I noweave(1), nodefs(1), cpif(1)
  158. .SH AUTHOR
  159. Norman Ramsey, Bellcore.
  160. Internet address \fBnorman@bellcore.com\fP.
  161.